home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / Moscow ML 1.42 / lib / Path.sig < prev    next >
Encoding:
Text File  |  1997-08-18  |  7.7 KB  |  196 lines  |  [TEXT/Moml]
  1. (* OS.Path -- SML Basis Library *)
  2.  
  3. exception Path
  4.  
  5. val parentArc    : string
  6. val currentArc   : string
  7.  
  8. val fromString   : string -> {isAbs : bool, vol : string, arcs : string list}
  9. val toString     : {isAbs : bool, vol : string, arcs : string list} -> string
  10.  
  11. val getVolume    : string -> string 
  12. val validVolume  : {isAbs : bool, vol : string} -> bool
  13. val getParent    : string -> string
  14.  
  15. val isAbsolute   : string -> bool
  16. val isRelative   : string -> bool
  17. val mkAbsolute   : string * string -> string
  18. val mkRelative   : string * string -> string
  19.  
  20. val concat       : string * string -> string
  21.  
  22. val mkCanonical  : string -> string
  23. val isCanonical  : string -> bool
  24.  
  25. val splitDirFile : string -> {dir : string, file : string}
  26. val joinDirFile  : {dir : string, file : string} -> string
  27. val dir          : string -> string
  28. val file         : string -> string
  29.  
  30. val splitBaseExt : string -> {base : string, ext : string option}
  31. val joinBaseExt  : {base : string, ext: string option} -> string
  32. val base         : string -> string    
  33. val ext          : string -> string option
  34.  
  35.  
  36. (* This module provides OS-independent functions for manipulating
  37.    strings that represent file names and paths in a directory
  38.    structure.  None of these functions accesses the actual filesystem.
  39.    
  40.    Definitions: 
  41.  
  42.    * An arc denotes a directory or file.  Under Unix or DOS, an arc may
  43.    have form "..", ".", "", or "abc", or similar.
  44.  
  45.    * An absolute path has a root: Unix examples include "/", "/a/b";
  46.    DOS examples include "\", "\a\b", "A:\a\b".  
  47.  
  48.    * A relative path is one without a root: Unix examples include
  49.    "..", "a/b"; DOS examples include "..", "a\b", "A:a\b".
  50.  
  51.    * A path has an associated volume.  Under Unix, there is only one
  52.    volume, whose name is "".  Under DOS, the volume names are "",
  53.    "A:", "C:", and similar.
  54.  
  55.    * A canonical path contains no occurrences of the empty arc "" or
  56.    the current arc ".", and contains or the parent arc ".." only at
  57.    the beginning and only if the path is relative.  
  58.  
  59.    * All functions (except concat) preserve canonical paths.  That is,
  60.    if all arguments are canonical, then so will the result be.
  61.  
  62.    * All functions are defined so that they work sensibly on canonical 
  63.    paths.
  64.  
  65.    * There are three groups of functions, corresponding to three ways
  66.    to look at paths, exemplified by the following paths:
  67.  
  68.        Unix:    d/e/f/a.b.c       and     /d/e/f/a.b.c 
  69.         DOS:     A:d\e\f\a.b.c     and     A:d\e\f\a.b.c     
  70.  
  71.    (1) A path consists of a sequence of arcs, possibly preceded by a
  72.        volume and a root:
  73.  
  74.                           vol  [--- arcs ---]        vol  root  [--- arcs ---]
  75.         ------------------------------------------------------------------ 
  76.     Unix examples:           d  e  f  a.b.c               /   d  e  f  a.b.c
  77.     DOS examples:     A:   d  e  f  a.b         A:     \   d  e  f  a.b
  78.  
  79.    (2) A path consists of a directory part and a (last) file name part:
  80.  
  81.                           directory   file            directory  file 
  82.         ------------------------------------------------------------------
  83.         Unix examples:    d/e/f       a.b.c           /d/e/f     a.b.c
  84.         DOS examples:     A:d\e\f     a.b             A:\d\e\f   a.b
  85.  
  86.    (3) A path consists of a base and an extension:
  87.  
  88.                           base       extension       base        extension
  89.         ------------------------------------------------------------------
  90.         Unix examples:    d/e/f/a.b      c           /d/e/f/a.b      c
  91.         DOS examples:     A:d\e\f\a      b           A:\d\e\f\a      b
  92.  
  93.  
  94.    GROUP 0: General functions on paths:
  95.  
  96.    [parentArc] is the arc denoting a parent directory: ".." under 
  97.    DOS and Unix.
  98.  
  99.    [currentArc] is the arc denoting the current directory: "." under 
  100.    DOS and Unix.
  101.  
  102.    [isRelative p] returns true if p is a relative path.
  103.  
  104.    [isAbsolute p] returns true if p is an absolute path.  
  105.    Equals not (isRelative p).
  106.  
  107.    [validVolume {isAbs, vol}] returns true if vol is a valid volume
  108.    name for an absolute path (if isAbs=true) resp. for a relative path
  109.    (if isAbs=false).  Under Unix, the only valid volume name is "";
  110.    under DOS the valid volume names are "", "a:", "b:", ..., and "A:",
  111.    "B:", ...
  112.  
  113.    [getParent p] returns a string denoting the parent directory of p.
  114.    It holds that getParent p = p if and only if p is a root. 
  115.  
  116.    [concat (p1, p2)] returns the path consisting of p1 followed by p2.
  117.    Does not preserve canonical paths: concat("a/b", "../c") equals
  118.    "a/b/../c".  This is because "a/b/../c" and "a/c" may not be
  119.    equivalent in the presence of symbolic links.  Raises Path if p2 is
  120.    not a relative path.
  121.  
  122.    [mkAbsolute(p1, p2)] returns the absolute path made by taking path
  123.    p2, then p1.  That is, returns p1 if p1 is absolute; otherwise
  124.    returns the canonicalized concatenation of p2 and p1.  Raises Path
  125.    if p2 is not absolute (even if p1 is absolute).
  126.  
  127.    [mkRelative(p1, p2)] returns p1 relative to p2.  That is, returns
  128.    p1 if p1 is already relative; otherwise returns the relative path
  129.    leading from p2 to p1.  Raises Path if p2 is not absolute (and even
  130.    if p1 is relative), or if p1 and p2 are both absolute but have
  131.    different roots.
  132.  
  133.    [mkCanonical p] returns a canonical path which is equivalent to p.
  134.    Redundant occurrences of the parent arc, the current arc, and the
  135.    empty arc are removed.  The canonical path will never be the empty
  136.    string; the empty path is converted to the current directory path
  137.    ("." under Unix and DOS).  
  138.  
  139.    [isCanonical p] is equal to (p = mkCanonical p).
  140.  
  141.  
  142.    GROUP 1: Manipulating volumes and arcs:
  143.  
  144.    [fromString s] returns {isAbs=false, vol, arcs} if the path p is
  145.    relative, and {isAbs=true, vol, arcs} if the path p is absolute.
  146.    In both cases vol is the volume name and arcs is the list of
  147.    (possibly empty) arcs of the path.  Under Unix, the volume name is
  148.    always the empty string ""; under DOS it will have form "A:", "C:",
  149.    or similar.
  150.  
  151.    [toString path] reconstitutes a path from its root (if any) and
  152.    arcs.  Raises Path if applied to a relative path whose first arc is
  153.    empty.  It holds that toString(fromString p) = p, except that in MS
  154.    DOS, slashes "/" in p will be replaced by backslashes "\".  It
  155.    holds that fromString (toString p) = p when no exception is raised.
  156.    It holds that isRelative(toString {isAbs=false, vol, arcs}) = true
  157.    when no exception is raised.
  158.  
  159.  
  160.    GROUP 2: Manipulating directory paths and file names:
  161.  
  162.    [splitDirFile p] returns {dir, file} where file is the last arc in
  163.    p, and dir is the path preceding that arc.  A typical use is to
  164.    split a path into the directory part (dir) and the filename (file).
  165.  
  166.    [joinDirFile {dir, file}] returns the path p obtained by extending
  167.    the path dir with the arc file.
  168.  
  169.    [dir p] equals #dir (splitDirFile p).
  170.  
  171.    [file p] equals #file (splitDirFile p).
  172.  
  173.  
  174.    GROUP 3: Manipulating file names and extensions:
  175.  
  176.    [splitBaseExt s] returns {base, ext} where ext = NONE if s has no
  177.    extension, and ext = SOME e if s has extension e; base is the part
  178.    of s preceding the extension.  A path s is considered having no
  179.    extension if its last arc contains no extension separator
  180.    (typically ".") or contains an extension separator only as its
  181.    leftmost character, or contains an extension separator as its
  182.    right-most character.  Hence none of "a.b/cd", "a/.login", "a.",
  183.    "..", "." and "." has an extension.
  184.  
  185.    [joinBaseExt {base, ext}] returns an arc composed of the base name
  186.    and the extension (if different from NONE).  It is a left inverse
  187.    of splitBaseExt, so joinBaseExt (splitBaseExt s) = s, but the
  188.    opposite does not hold (since the extension may be empty, or may
  189.    contain extension separators).
  190.  
  191.    [ext s] equals #ext (splitBaseExt s).
  192.  
  193.    [base s] equals #base (splitBaseExt s).
  194. *)
  195.  
  196.